devfandomcom-20200223-history
I18n-js
I18n-js is a library for loading a script's messages, stored as JSON, ready for said script to use. Not only does it allow messages to be split out of the main code containing all the logic, it handles language fallbacks as well. Usage I18n page To use I18n-js, you will need to set up your messages in the appropriate place and in the correct format. The message loader will expect your messages to be in a page such as MediaWiki:Custom-PAGENAME/i18n.json here on Dev Wiki, where PAGENAME should be the name of your script. the format of your messages should be as follows: { "en": { "name": "value" }, "pl": { "name": "value" } } Importing the script Once you're all set up, simply import MediaWiki:I18n-js/code.js into your script. There are a few ways to achieve this, but they generally fall into 1 of 2 categories: 1. Import the script using importArticles or other import function that provides no indication of when the script has finished loading. If you use this method, you can listen for the dev.i18n event using mw.hook: // register the hook before the import to avoid race conditions mw.hook('dev.i18n').add(function (i18n) { // i18n is a shortcut to window.dev.i18n }); importArticle({ type: 'script', article: 'u:dev:I18n-js/code.js' }); 2. Import the script using a function that provides a callback, such as $.getScript. If you're using this method, you use the callback and access window.dev.i18n within: // TODO: Loading your messages Now the script is loaded you're ready to load your messages. This is achieved using the loadMessages method of window.dev.i18n which returns and instance of i18n. This will also cache said instance in case you attempt to load the messages again for any reason: // name is the PAGENAME part of http://dev.wikia.com/wiki/Custom-PAGENAME/i18n.json i18n.loadMessages(name).done(function (i18n) { // use your i18n instance here }); i18n usage i18n controls access to your individual messages as well as the language it tries to translate them into. It defines the following 4 methods: * useLang(code): Set the default language to code, e.g. 'pt'. By default, the language will be the value of wgUserLanguage. * useContentLang(): Set the default language to the value of wgContentLanguage. * useUserLang(): Set the default language to the value of wgUserLanguage. * msg(message, arg1, arg2, arg3, ...): Create a Message instance representing the message in the closest language to the default language possible with any arguments substituted in. See message usage for details on how to use this. message usage message represents a translated message in the closest language to the default language set in the i18n instance as possible. If a translation could not be found in the requested language, then it will try a fallback language instead, until it falls back to English. If the English translation could not be found, then it will contain the name of the message wrapped in < ... >, e.g. . If your message uses arguments, these should be specified in the form $n where n is a integer greater than 0, e.g, 'Hello, $1, my name is $2'. There are 3 methods available for outputting the message stored in the Message instance: * plain(): This outputs the message as is with no further processing. * parse(): This outputs the message with all basic wikitext links converted into HTML. This supports links in the formats: ** text ** pagename ** text * escape(): This outputs the message with any HTML characters escaped. Editing your messages JSON can be a bit tricky to edit, especially if you're unfamiliar with the syntax. To improve the editing experience, a dedicated editor is being worked on to enable adding or modifying translations to be as quick and pain free as possible. Change log ;21 February 2017 * Prevent the script loading multiples times and causing the cache to be lost. ;16 February 2017 * Switched to factory method instead of constructors. * Fixed argument handling to start at $1 instead of $0. * Fixed link parsing for absolute URLs. ;15 February 2017 * Improved fallback behaviour to mirror that of MediaWiki. * Added argument handling. * Added basic parsing functionality. ;13 February 2017 * Initial release.